<!--
  ****************************************************************************
  * Copyright 2018-2024,2025 Thomas E. Dickey                                *
  * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_initscr.3x,v 1.92 2025/02/02 00:01:55 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_initscr 3x 2025-02-01 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">

</HEAD>
<BODY>
<H1 class="no-header">curs_initscr 3x 2025-02-01 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>                 Library calls                <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>initscr</STRONG>,  <STRONG>newterm</STRONG>,  <STRONG>endwin</STRONG>, <STRONG>isendwin</STRONG>, <STRONG>set_term</STRONG>, <STRONG>delscreen</STRONG> - initialize,
       manipulate, or tear down <EM>curses</EM> terminal interface


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>

       <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>initscr(void);</STRONG>
       <STRONG>int</STRONG> <STRONG>endwin(void);</STRONG>

       <STRONG>bool</STRONG> <STRONG>isendwin(void);</STRONG>

       <STRONG>SCREEN</STRONG> <STRONG>*</STRONG> <STRONG>newterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>type</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG> <EM>outf</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG> <EM>inf</EM><STRONG>);</STRONG>
       <STRONG>SCREEN</STRONG> <STRONG>*</STRONG> <STRONG>set_term(SCREEN</STRONG> <STRONG>*</STRONG> <EM>new</EM><STRONG>);</STRONG>
       <STRONG>void</STRONG> <STRONG>delscreen(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>

</PRE><H3><a name="h3-initscr">initscr</a></H3><PRE>
       <STRONG>initscr</STRONG> determines the terminal  type  and  initializes  the  library's
       <EM>SCREEN</EM>,  <EM>WINDOW</EM>,  and  other data structures.  It is normally the first
       <EM>curses</EM> function call a program performs.  However, an application  with
       unusual needs might employ a few other <EM>curses</EM> functions beforehand:

       <STRONG>o</STRONG>   <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> to set up soft-label keys;

       <STRONG>o</STRONG>   <STRONG><A HREF="curs_util.3x.html">filter(3x)</A></STRONG>  if  the  program  is  designed  to operate in a process
           pipeline;

       <STRONG>o</STRONG>   <STRONG><A HREF="curs_kernel.3x.html">ripoffline(3x)</A></STRONG> to reserve up to five lines at the top and/or bottom
           of  the  screen  from  management  by  <STRONG>stdscr</STRONG>,  the standard <EM>curses</EM>
           window; and

       <STRONG>o</STRONG>   <STRONG><A HREF="curs_util.3x.html">use_env(3x)</A></STRONG> and/or <STRONG><A HREF="curs_util.3x.html">use_tioctl(3x)</A></STRONG> to configure use of  the  process
           environment  and  operating system's terminal driver, respectively,
           when determining the dimensions of the terminal display.

       Further, a <EM>curses</EM> program might call <STRONG>newterm</STRONG> prior  to  or  instead  of
       <STRONG>initscr</STRONG> in two specialized cases described in its subsection below.

       <STRONG>initscr</STRONG>  causes  the  first  <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>  call to clear the screen.  If
       errors occur, <STRONG>initscr</STRONG> writes an appropriate diagnostic message  to  the
       standard  error  stream  and  exits; otherwise, it returns a pointer to
       <STRONG>stdscr</STRONG>.


</PRE><H3><a name="h3-newterm">newterm</a></H3><PRE>
       An application that manages multiple terminals should call <STRONG>newterm</STRONG> once
       for each such device <EM>instead</EM> of <STRONG>initscr</STRONG>.  <STRONG>newterm</STRONG>'s arguments are

       <STRONG>o</STRONG>   the  <EM>type</EM>  of  the  associated  terminal,  or  <EM>NULL</EM> to use the <EM>TERM</EM>
           environment variable;

       <STRONG>o</STRONG>   an output stream <EM>outf</EM> connected to the terminal; and

       <STRONG>o</STRONG>   an input stream <EM>inf</EM>  connected  to  the  terminal.   It  returns  a
           variable  of  structure  type  <EM>SCREEN</EM>  <STRONG>*</STRONG>, which should be saved for
           later use with <STRONG>set_term</STRONG> and <STRONG>delscreen</STRONG>.

       <STRONG>newterm</STRONG> passes the file descriptor of the output stream to the <EM>terminfo</EM>
       function <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>, which returns a pointer to a <EM>TERMINAL</EM> structure
       that <STRONG>newterm</STRONG> stores in the <EM>SCREEN</EM> it returns to the application.

       An application that needs to inspect a terminal type's capabilities, so
       that  it  can  continue  to run in a line-oriented mode if the terminal
       cannot support a screen-oriented program, would also use  <STRONG>newterm</STRONG>.   If
       at most one terminal connection is needed, the programmer could perform
       such a capability test, decide which mode in  which  to  operate,  then
       call  <STRONG>delscreen</STRONG>  on  the  pointer returned by <STRONG>newterm</STRONG>, and proceed with
       either <STRONG>initscr</STRONG> or a non-<EM>curses</EM> interface.


</PRE><H3><a name="h3-endwin">endwin</a></H3><PRE>
       The program must also call <STRONG>endwin</STRONG> for each terminal being  used  before
       exiting  from <EM>curses</EM>.  If <STRONG>newterm</STRONG> is called more than once for the same
       terminal, the first terminal referred to must be the last one for which
       <STRONG>endwin</STRONG> is called.

       A  program  should always call <STRONG>endwin</STRONG> before exiting the application or
       temporarily suspending <EM>curses</EM>'s management of the terminal.  <STRONG>endwin</STRONG>:

       <STRONG>o</STRONG>   resets colors to correspond with the default color pair 0,

       <STRONG>o</STRONG>   moves the cursor to the lower left-hand corner of the screen,

       <STRONG>o</STRONG>   clears the remainder of the  line  so  that  it  uses  the  default
           colors,

       <STRONG>o</STRONG>   sets the cursor to normal visibility (see <STRONG><A HREF="curs_kernel.3x.html">curs_set(3x)</A></STRONG>),

       <STRONG>o</STRONG>   if  applicable, stops cursor-addressing mode using the <STRONG>exit_ca_mode</STRONG>
           (<STRONG>rmcup</STRONG>) terminal capability, and

       <STRONG>o</STRONG>   restores terminal modes (see <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG>).

       Calling <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> after a temporary suspension causes
       <EM>curses</EM> to resume managing the terminal.


</PRE><H3><a name="h3-isendwin">isendwin</a></H3><PRE>
       <STRONG>isendwin</STRONG>  returns <STRONG>TRUE</STRONG> if <STRONG>endwin</STRONG> has been called without any subsequent
       calls to <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, and <STRONG>FALSE</STRONG> otherwise.


</PRE><H3><a name="h3-set_term">set_term</a></H3><PRE>
       <STRONG>set_term</STRONG> re-orients the <EM>curses</EM> library's operations to another terminal
       when the application has arranged to manage more than one with <STRONG>newterm</STRONG>.
       <STRONG>set_term</STRONG> expects a <EM>SCREEN</EM> pointer previously returned by <STRONG>newterm</STRONG> as  an
       argument,  and  returns  the previous one.  <STRONG>set_term</STRONG> is the only <EM>curses</EM>
       API function that manipulates <EM>SCREEN</EM> pointers; all others  affect  only
       the current terminal.


</PRE><H3><a name="h3-delscreen">delscreen</a></H3><PRE>
       <STRONG>delscreen</STRONG>  frees  the  storage  backing  the  supplied  <EM>SCREEN</EM>  pointer
       argument.  <STRONG>endwin</STRONG> does not, so that an application can resume  managing
       a  terminal  with  <EM>curses</EM>  after  a (possibly conditional or temporary)
       suspension; see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>.  Call <STRONG>delscreen</STRONG> after  <STRONG>endwin</STRONG>  when  a
       particular <EM>SCREEN</EM> structure is no longer needed.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       <STRONG>endwin</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.

       In <EM>ncurses</EM>,

       <STRONG>o</STRONG>   <STRONG>endwin</STRONG> returns <STRONG>ERR</STRONG> if

           <STRONG>o</STRONG>   the terminal was not initialized,

           <STRONG>o</STRONG>   <STRONG>endwin</STRONG> is called more than once without updating the screen, or

           <STRONG>o</STRONG>   <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG> returns <STRONG>ERR</STRONG>.

       <STRONG>o</STRONG>   <STRONG>newterm</STRONG>  returns  <STRONG>ERR</STRONG>  if it cannot allocate storage for the <EM>SCREEN</EM>
           data structure or the top-level windows  thereof:  <STRONG>curscr</STRONG>,  <STRONG>newscr</STRONG>,
           and <STRONG>stdscr</STRONG>.

       Functions  that  return  pointers  return  <EM>NULL</EM>  on error.  In <EM>ncurses</EM>,
       <STRONG>set_term</STRONG> does not fail, and <STRONG>initscr</STRONG> exits the application  if  it  does
       not operate successfully.


</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
       <EM>ncurses</EM>  establishes signal handlers when a function that initializes a
       <EM>SCREEN</EM>, either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>, is first called.  Applications  that
       wish  to  handle  the  following signals themselves should set up their
       corresponding handlers <EM>after</EM> initializing the screen.

       <EM>SIGINT</EM> <EM>ncurses</EM>'s handler <EM>attempts</EM> to  clean  up  the  screen  on  exit.
              Although it <EM>usually</EM> works as expected, there are limitations.

              <STRONG>o</STRONG>   Walking the <EM>SCREEN</EM> list is unsafe, since all list management
                  is done without any signal blocking.

              <STRONG>o</STRONG>   When an application has been built with the <STRONG>_</STRONG><EM>REENTRANT</EM> macro
                  defined  (and  corresponding  system support), <STRONG>set_term</STRONG> uses
                  functions that could deadlock or misbehave in other ways.

              <STRONG>o</STRONG>   <STRONG>endwin</STRONG> calls other functions, many of which use <STRONG>stdio(3)</STRONG>  or
                  other library functions that are clearly unsafe.

       <EM>SIGTERM</EM>
              <EM>ncurses</EM>  uses  the  same  handler  as  for <EM>SIGINT</EM>, with the same
              limitations.  It is not mentioned in X/Open Curses, but is  more
              suitable  for  this  purpose  than  <EM>SIGQUIT</EM>  (which  is  used in
              debugging).

       <EM>SIGTSTP</EM>
              <EM>ncurses</EM>'s handler manages the  terminal-generated  stop  signal,
              used  in  job  control.   When  resuming  the  process,  <EM>ncurses</EM>
              discards  pending  input  with  <STRONG><A HREF="curs_util.3x.html">flushinp(3x)</A></STRONG>  and  repaints  the
              screen,  assuming  that it has been completely altered.  It also
              updates the saved terminal modes with <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>.

       <EM>SIGWINCH</EM>
              <EM>ncurses</EM>  handles  changes  to  the  terminal's  window  size,  a
              phenomenon  ignored  in  standardization  efforts.   It  sets  a
              (signal-safe) variable that is later tested  by  <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>  and
              <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG>.

              <STRONG>o</STRONG>   <STRONG>wgetch</STRONG> returns the key code <STRONG>KEY_RESIZE</STRONG>.

              <STRONG>o</STRONG>   <STRONG>wget_wch</STRONG>  returns <STRONG>KEY_CODE_YES</STRONG> and sets its <EM>wch</EM> parameter to
                  <STRONG>KEY_RESIZE</STRONG>.

              At the same time, <EM>ncurses</EM> calls  <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>  to  adjust  the
              standard  screen  <STRONG>stdscr</STRONG>,  and  update  global variables such as
              <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG>.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       X/Open Curses Issue 4 describes these functions.  It specifies no error
       conditions for them.


</PRE><H3><a name="h3-Differences">Differences</a></H3><PRE>
       X/Open  Curses  specifies  that  portable  applications  must  not call
       <EM>initscr</EM> more than once.

       <STRONG>o</STRONG>   The portable way to use <EM>initscr</EM> is  once  only,  using  <EM>refresh</EM>  to
           restore the screen after <EM>endwin</EM>.

       <STRONG>o</STRONG>   <EM>ncurses</EM> permits use of <EM>initscr</EM> after <EM>endwin</EM>.

       <EM>initscr</EM>  in  BSD,  from  its inception (1980) through the Net/2 release
       (1991) returned <EM>ERR</EM> cast to a <EM>WINDOW</EM> pointer when detecting  an  error.
       4.4BSD  (1995)  instead  returned  a  null pointer.  Neither exited the
       application.  It is safe but redundant to check  the  return  value  of
       <EM>initscr</EM> in X/Open Curses.

       Calling  <EM>endwin</EM>  does not dispose of the memory allocated by <EM>initscr</EM> or
       <EM>newterm</EM>.  Deleting a <EM>SCREEN</EM> provides a way to do this.

       <STRONG>o</STRONG>   X/Open Curses does not say what happens to <EM>WINDOW</EM>s  when  <EM>delscreen</EM>
           "frees  storage  associated  with  the  <EM>SCREEN</EM>"  nor  does the SVr4
           documentation help, adding that it should be called after <EM>endwin</EM> if
           a <EM>SCREEN</EM> is no longer needed.

       <STRONG>o</STRONG>   However,  <EM>WINDOW</EM>s are implicitly associated with a <EM>SCREEN</EM>, so it is
           reasonable to expect <EM>delscreen</EM> to dispose of them.

       <STRONG>o</STRONG>   SVr4 deletes the standard <EM>WINDOW</EM> structures <EM>stdscr</EM>  and  <EM>curscr</EM>  as
           well as a work area <EM>newscr</EM>.  It ignores other windows.

       <STRONG>o</STRONG>   Since  version  4.0  (1996),  <EM>ncurses</EM>  has maintained a list of all
           windows for each screen, using that  information  to  delete  those
           windows when <EM>delscreen</EM> is called.

       <STRONG>o</STRONG>   NetBSD  copied  this  feature of <EM>ncurses</EM> in 2001.  <EM>PDCurses</EM> follows
           the SVr4 model, deleting only the standard <EM>WINDOW</EM> structures.


</PRE><H3><a name="h3-High-level-versus-Low-level">High-level versus Low-level</a></H3><PRE>
       Different implementations may disagree  regarding  the  level  of  some
       functions.   For  example,  <EM>SCREEN</EM>  (returned  by <EM>newterm</EM>) and <EM>TERMINAL</EM>
       (returned by  <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>)  hold  file  descriptors  for  the  output
       stream.  If an application switches screens using <EM>set</EM><STRONG>_</STRONG><EM>term</EM>, or switches
       terminals using <STRONG><A HREF="curs_terminfo.3x.html">set_curterm(3x)</A></STRONG>, applications which use the output file
       descriptor  can  have  different  behavior depending on which structure
       holds the corresponding descriptor.

       <STRONG>o</STRONG>   NetBSD's  <EM>baudrate</EM>  function  uses  the  descriptor  in   <EM>TERMINAL</EM>.
           <EM>ncurses</EM> and SVr4 use the descriptor in <EM>SCREEN</EM>.

       <STRONG>o</STRONG>   NetBSD  and <EM>ncurses</EM> use the descriptor in <EM>TERMINAL</EM> for terminal I/O
           modes, e.g., <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">def_prog_mode(3x)</A></STRONG>.  SVr4 uses  the
           descriptor in <EM>SCREEN</EM>.

   <STRONG>Unset</STRONG> <EM>TERM</EM> <STRONG>Variable</STRONG>
       If  the  <EM>TERM</EM>  variable  is  missing  or  empty, <EM>initscr</EM> uses the value
       "unknown", which normally corresponds to  a  terminal  entry  with  the
       <STRONG>generic</STRONG> (<STRONG>gn</STRONG>) capability.  Generic entries are detected by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>
       and cannot be used for full-screen  operation.   Other  implementations
       may handle a missing/empty <EM>TERM</EM> variable differently.


</PRE><H3><a name="h3-Signal-Handlers">Signal Handlers</a></H3><PRE>
       Quoting X/Open Curses Issue 7, section 3.1.1:

            Curses  implementations  may  provide  for special handling of the
            SIGINT, SIGQUIT, and  SIGTSTP  signals  if  their  disposition  is
            SIG_DFL at the time <EM>initscr</EM>() is called...

            Any  special  handling  for these signals may remain in effect for
            the  life  of  the  process  or  until  the  process  changes  the
            disposition of the signal.

            None  of the Curses functions are required to be safe with respect
            to signals...

       Section "NOTES" above discusses <EM>ncurses</EM>'s signal handlers.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,    <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,     <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>,     <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>,
       <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>



ncurses 6.5                       2025-02-01                  <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-initscr">initscr</a></li>
<li><a href="#h3-newterm">newterm</a></li>
<li><a href="#h3-endwin">endwin</a></li>
<li><a href="#h3-isendwin">isendwin</a></li>
<li><a href="#h3-set_term">set_term</a></li>
<li><a href="#h3-delscreen">delscreen</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-Differences">Differences</a></li>
<li><a href="#h3-High-level-versus-Low-level">High-level versus Low-level</a></li>
<li><a href="#h3-Signal-Handlers">Signal Handlers</a></li>
</ul>
</li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
